001 /* 002 * Copyright 2004-2006 Stephen J. McConnell. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or 013 * implied. 014 * 015 * See the License for the specific language governing permissions and 016 * limitations under the License. 017 */ 018 019 package net.dpml.component; 020 021 import java.rmi.Remote; 022 import java.rmi.RemoteException; 023 import java.lang.reflect.InvocationTargetException; 024 025 import net.dpml.state.State; 026 import net.dpml.state.StateListener; 027 import net.dpml.state.UnknownOperationException; 028 import net.dpml.state.UnknownTransitionException; 029 030 /** 031 * Provider holder. 032 * 033 * @author <a href="http://www.dpml.net">Digital Product Meta Library</a> 034 * @version 1.0.2 035 */ 036 public interface Provider extends Remote 037 { 038 /** 039 * Return a parent provider. 040 * @return the parent provider or null if this is a root provider 041 * @exception RemoteException if a remote I/O occurs 042 */ 043 Provider getParent() throws RemoteException; 044 045 /** 046 * Return the current status of the provider. 047 * @return the provider status 048 * @exception RemoteException if a remote I/O occurs 049 */ 050 Status getStatus() throws RemoteException; 051 052 /** 053 * Return a provider capable of supporting the requested service. 054 * @param service the service descriptor 055 * @return a component matching the requested service 056 * @exception ServiceNotFoundException if no component could found 057 * @exception RemoteException if a remote I/O occurs 058 */ 059 Provider lookup( Service service ) throws ServiceNotFoundException, RemoteException; 060 061 /** 062 * Returns the current state of the control. 063 * @return the current runtime state 064 * @exception RemoteException if a remote I/O error occurs 065 */ 066 State getState() throws RemoteException; 067 068 /** 069 * Add a state listener to the control. 070 * @param listener the state listener 071 * @exception RemoteException if a remote I/O error occurs 072 */ 073 void addStateListener( StateListener listener ) throws RemoteException; 074 075 /** 076 * Remove a state listener from the control. 077 * @param listener the state listener 078 * @exception RemoteException if a remote I/O error occurs 079 */ 080 void removeStateListener( StateListener listener ) throws RemoteException; 081 082 /** 083 * Return the runtime value associated with this instance. 084 * @param isolate if TRUE the value returned is a proxy exposing the 085 * service interfaces declared by the component type otherwise 086 * the instance value is returned. 087 * @return the value 088 * @exception RemoteException if a remote I/O error occurs 089 */ 090 Object getValue( boolean isolate ) throws RemoteException; 091 092 /** 093 * Apply a transition to the instance. 094 * @param key the transition name 095 * @return the state established as a result of applying the transition 096 * @exception UnknownTransitionException if the supplied key does not map to an available transition 097 * @exception InvocationTargetException if an invocation error occurs 098 * @exception RemoteException if a remote I/O error occurs 099 */ 100 State apply( String key ) 101 throws UnknownTransitionException, InvocationTargetException, RemoteException; 102 103 /** 104 * Invoke an operation on the instance. 105 * @param name the operation name 106 * @param args operation arguments 107 * @return the result of the operation invocation 108 * @exception UnknownOperationException if the supplied key does not map to an available operation 109 * @exception InvocationTargetException if an invocation error occurs 110 * @exception RemoteException if a remote I/O error occurs 111 */ 112 Object exec( String name, Object[] args ) 113 throws UnknownOperationException, InvocationTargetException, RemoteException; 114 115 /** 116 * Invoke an operation on the instance. 117 * @param method the operation name 118 * @param args operation arguments 119 * @return the result of the operation invocation 120 * @exception UnknownOperationException if the supplied key does not map to an available operation 121 * @exception InvocationTargetException if an invocation error occurs 122 * @exception IllegalStateException if the component state does not expose the operation 123 * @exception RemoteException if a remote I/O error occurs 124 */ 125 Object invoke( String method, Object[] args ) 126 throws UnknownOperationException, InvocationTargetException, 127 IllegalStateException, RemoteException; 128 129 }